BigDFT.Visualization module

This module has the routines and data structures necessary to allow one to generate visualizations of a atomic systems. We also include helper routines for generating colors.

class InlineVisualizer(xsize=400, ysize=300, nrow=1, ncol=1)[source]

This class allows for a quick viewing of BigDFT systems using the py3Dmol package.


the width of the picture in pixels.




the height of the picture in pixels.




if present, the number of rows for displaying a grid of structures.




if present, the number of columns for displaying a grid of structures.



display_system(*syslist, **kwargs)[source]

Display an animation of a sequence of systems. The colordict can be used to color each fragment. When only one system is passed it will remain still.

  • syslist (BigDFT.Systems.System) – the systems to visualize.

  • colordict (dict) – a dictionary from fragment ids to hex colors, can also be a list of dicts (one for each system) if using a grid.

  • field_vals (list) – values of the field to decide colors of the keys

  • cartoon (bool) – set to True to use the cartoon view. This only works if atom names and residues are properly defined.

  • gridlist (list) – if present, defines the row and column indices for visualizing multiple systems on a grid.

  • show (bool) – you can explicitly defer showing.

class VMDGenerator(representation='CPK', color=16)[source]

This class contains the routines you would use for visualization of a system using the VMD program.


the vmd representation to draw with.




the default color to draw with.



visualize_fragments(system, scriptfile, geomfile, fragcolors=None)[source]

This generates a script for visualizing the fragmentation of a system using VMD.

  • system (BigDFT.Systems.System) – the system to visualize.

  • scriptfile (str) – the name of the file to write the vmd script to (usually has extension .tcl)

  • geomfile (str) – the filename for where to write an xyz file of the system.

  • fragcolors (dict) – optionally, a dictionary from fragment ids to fragment colors. Colors are integers between 0 and 32.

get_distinct_colors(keys, name='tab20', fuzz=True)[source]

This generates a dictionary of distinct colors based on a matplotlib colormap.

  • keys (list) – a list of keys.

  • name (str) – the name of the matplotlib colormap to use.

  • fuzz (bool) – some color maps (included tab20) only have a distinct set of colors. The fuzz option adds increased randomness to make up for this.


a dictionary mapping matplotlib keys to RGB colors.

Return type:


truncate_colormap(cmap, compressed_values=None, vmin=0.0, vmax=1.0, N=- 1)[source]

Truncate a colormap from a given cmap. Taken from how-to-use-and-plot-only-a-part-of-a-colorbar-in-matplotlib.


Builds a dictionary of colors for a system where each atom is its own fragment. This uses the built in colors of jmol.


a dictionary mapping fragment ids to colors.

Return type:


get_colordict(keys, field_vals=None, vmin=None, vmax=None, colorcode=None)[source]

Build a dictionary of colors for each of the keys. If the field_dict is provided, order the colors of the keys in terms of the sorting of the filed values

  • keys (list) – keys of the color dictionary

  • field_vals (list) – values of the field to decide the colors of the keys

  • vmin (float) – minimum value of the colors. Useful to extend the range below the minimum of field_vals.

  • vmax (float) – maximum value of the colors. Useful to extend the range below the maximum of field_vals.

  • colorcode (str) – the string of the colorcode. Default is ‘rainbow’ if no field_vals are present. If field_vals have negative data, default is seismic. Otherwise Reds.


the dictionary of the keys, and the corresponding colors.

The dictionary contains also special keys arguments to be passed to the colorbar method of matplotlib:

  • ’__mappable__’, which is associated the reference to the matplotlib.ScalarMappable instance that is associated to the colordict. This instance can be useful to draw colorbars associated to such a colordict.

Return type:



Input a string without hash sign of RGB hex digits to compute complementary contrasting color such as for fonts. Function borrowed from determine-font-color-based-on-background-color


hstr (str) – the color string, preferably in hex.


string of the contrasting color, black or white.

Return type:



The following is an example of module usage:

"""Visualization Example"""
from BigDFT.Systems import System
from BigDFT.Fragments import Fragment
from BigDFT.IO import XYZReader

# Read in a system.
sys = System()
with XYZReader("SiO") as ifile:
    for i, at in enumerate(ifile):
        sys["FRA:"+str(i)] = Fragment([at])

# Display the system.
viz = InlineVisualizer(400, 300)

# Change the colors
colordict = get_distinct_colors(list(sys))
viz.display_system(sys, colordict=colordict)